<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-type" content="text/html;charset=UTF-8" />
<title>Parser v 8.9 Documentation</title>
</head>

<body style="white-space: pre; font-family: monospace;">
<a name="top"></a><div align="center">Parser</div><div align="center">v 8.9</div>
<div align="center">By: Craig Williams</div>

<b>Index</b>

<a href="#1.0">1.0 - Overview</a>
    <a href="#1.0">The Parser is designed to be/have:</a>
        <a href="#port">Portable</a>
        <a href="#noco">No Conditional Compilation</a>
        <a href="#simp">Simple To Use</a>
        <a href="#noob">No Obsecure Data Types</a>
        <a href="#noma">No Obsecure Macros</a>
        <a href="#docu">Documented</a>
        <a href="#nota">No Tabs</a>
        <a href="#bloc">Block Formatting/Alignment</a>
        <a href="#dyna">Dynamic, Fast, and Safe</a>
        <a href="#acom">A Complete Package in one File</a>
        <a href="#tfos">Truly Free - Public Domain</a>
    <a href="#wdiff">How is this Parser different?</a>

<a href="#2.0">2.0 - Features</a>
    <a href="#2.01">2.01 - File Handling</a>
    <a href="#2.02">2.02 - Tokens &amp; Token Sets</a>
        <a href="#2.02">Token Parameters/Definable Logic</a>
            <a href="#Return">Return</a>
            <a href="#switchto">switchto</a>
            <a href="#ignore">ignore</a>
                <a href="#program1">Sample Program: New Line Counter</a>
            <a href="#fun">fun</a>
            <a href="#params">params</a>
        <a href="#tsets">Token Sets</a>
            <a href="#program2">Sample Program: Print comments and Strings</a>
    <a href="#2.03">2.03 - Text Mode Functions</a>
    <a href="#2.04">2.04 - Binary Mode Functions</a>
    <a href="#2.05">2.05 - Function Callbacks</a>
    <a href="#2.06">2.06 - String Manipulation Functions</a>
    <a href="#2.07">2.07 - Options/Configuration</a>
    <a href="#2.08">2.08 - Search Methods</a>
        <a href="#lin">Linear</a>
        <a href="#glob">Globbing</a>
        <a href="#regex">RegEx</a>
    <a href="#2.09">2.09 - State Management</a>
        <a href="#manual">Manual</a>
        <a href="#stack">Stack</a>
    <a href="#2.10">2.10 - C++ Wrapper</a>

<a href="#3.0">3.0 - Using the Parser</a>
    <a href="#3.1">3.1 - Compiling the Parser</a>
    <a href="#3.2">3.2 - Initialization</a>
    <a href="#3.3">3.3 - Setting up the Token Set</a>
    <a href="#3.4">3.4 - Parsing the file</a>
    <a href="#3.5">3.5 - Deinitialization</a>

<a href="#4.0">4.0 - Functions</a>
    <a href="#4.1">4.1 - Public Parser Functions</a>
        <a href="#4.1.01">4.1.01 - AddTokenSep()</a>
        <a href="#4.1.02">4.1.02 - AddTokenSeparator()</a>
        <a href="#4.1.03">4.1.03 - AddTokenSet()</a>

        <a href="#4.1.04">4.1.04 - End()</a>
        <a href="#4.1.05">4.1.05 - ErrorCode()</a>

        <a href="#4.1.06">4.1.06 - GetFilePosition()</a>
        <a href="#4.1.07">4.1.07 - GetFileSize()</a>
        <a href="#4.1.08">4.1.08 - GetParams()</a>
        <a href="#4.1.09">4.1.09 - GetParserState()</a>
        <a href="#4.1.10">4.1.10 - GetTokenSet()</a>
        <a href="#4.1.11">4.1.11 - GrabBinaryFloat()</a>
        <a href="#4.1.12">4.1.12 - GrabBinaryInt()</a>
        <a href="#4.1.13">4.1.13 - GrabByte()</a>
        <a href="#4.1.14">4.1.14 - GrabBytes()</a>
        <a href="#4.1.15">4.1.15 - GrabFloat()</a>
        <a href="#4.1.16">4.1.16 - GrabInt()</a>
        <a href="#4.1.17">4.1.17 - GrabToken()</a>

        <a href="#4.1.18">4.1.18 - LoadFile()</a>
        <a href="#4.1.19">4.1.19 - LoadMemory()</a>
        <a href="#4.1.20">4.1.20 - LoadMemoryLen()</a>

        <a href="#4.1.21">4.1.21 - ParserDeInit()</a>
        <a href="#4.1.22">4.1.22 - ParserDisable()</a>
        <a href="#4.1.23">4.1.23 - ParserEnable()</a>
        <a href="#4.1.24">4.1.24 - ParserInit()</a>
        <a href="#4.1.25">4.1.25 - ParserIsEnabled()</a>
        <a href="#4.1.26">4.1.26 - ParserMemoryUsage()</a>
        <a href="#4.1.27">4.1.27 - PeekByte()</a>
        <a href="#4.1.28">4.1.28 - PeekToken()</a>
        <a href="#4.1.29">4.1.29 - PopParserState()</a>
        <a href="#4.1.30">4.1.30 - PrintErrorCode()</a>
        <a href="#4.1.31">4.1.31 - PushParserState()</a>

        <a href="#4.1.32">4.1.32 - Seek()</a>
        <a href="#4.1.33">4.1.33 - SetFilePosition()</a>
        <a href="#4.1.34">4.1.34 - SetParserState()</a>
        <a href="#4.1.35">4.1.35 - SetTokenSet()</a>

        <a href="#4.1.36">4.1.36 - GenericDiscard()</a>

    <a href="#4.2">4.2 - String Manipulation Functions</a>
        <a href="#4.2.01">4.2.01 - RemoveWhiteSpaces()</a>
        <a href="#4.2.02">4.2.02 - ToUpper()</a>
        <a href="#4.2.03">4.2.03 - ToLower()</a>
        <a href="#4.2.04">4.2.04 - Dup()</a>
        <a href="#4.2.05">4.2.05 - DupLen()</a>
        <a href="#4.2.06">4.2.06 - DupRange()</a>
        <a href="#4.2.07">4.2.07 - DupRangeFile()</a>
        <a href="#4.2.08">4.2.08 - Cmp()</a>

    <a href="#4.3">4.3 - Private Parser Functions</a>
        <a href="#4.3.01">4.3.01 - BuildRange()</a>
        <a href="#4.3.02">4.3.02 - Compile()</a>
        <a href="#4.3.03">4.3.03 - DisableRegEx()</a>
        <a href="#4.3.04">4.3.04 - DiscardWildcard()</a>
        <a href="#4.3.05">4.3.05 - EnableRegEx()</a>
        <a href="#4.3.06">4.3.06 - EnableWildcard()</a>
        <a href="#4.3.07">4.3.07 - ForwardSearch()</a>
        <a href="#4.3.08">4.3.08 - ForwardSearchReg()</a>
        <a href="#4.3.09">4.3.09 - GrabLeftover()</a>
        <a href="#4.3.10">4.3.10 - GrabNextChunk()</a>
        <a href="#4.3.11">4.3.11 - GTChar*()</a>
        <a href="#4.3.12">4.3.12 - HandleEscapes()</a>
        <a href="#4.3.13">4.3.13 - InvalidRegEx()</a>
        <a href="#4.3.14">4.3.14 - PDupRangeFile()</a>
        <a href="#4.3.15">4.3.15 - PreserveBufferState()</a>
        <a href="#4.3.16">4.3.16 - PreserveTSetHistory()</a>
        <a href="#4.3.17">4.3.17 - PrintCompiled()</a>
        <a href="#4.3.18">4.3.18 - ProcessToken()</a>
        <a href="#4.3.19">4.3.19 - ProcessTokenWild()</a>
        <a href="#4.3.20">4.3.20 - ReadBinary()</a>
        <a href="#4.3.21">4.3.21 - RebuildHash()</a>
        <a href="#4.3.22">4.3.22 - RestoreBufferState()</a>
        <a href="#4.3.23">4.3.23 - RestoreTSetHistory()</a>
        <a href="#4.3.24">4.3.24 - ShiftRight()</a>
        <a href="#4.3.25">4.3.25 - SortTokenSet()</a>
        <a href="#4.3.26">4.3.26 - UpdateThreads()</a>
        <a href="#4.3.27">4.3.27 - WriteThreadBefore()</a>

<a href="#5.0">5.0 - Define List</a>
<a href="#6.0">6.0 - Known Bugs</a>
<a href="#7.0">7.0 - Planned Features</a>
<a href="#8.0">8.0 - Change Log</a>


<div align="center"><a name="1.0"><font color="blue"><b>1.0 - Overview</b></font></a>  -  <a href="#top">Top of Page</a></div>
    The Parser was originally designed to meet my own needs. Since it's
      original creation, the parser has been expanding into something simply
      beautiful. A lot of time and though has been put into the library, to
      ensure that it behaves as it should.

    The library is entirely written by me, and release to the Public Domain

    One quick note. This entire document was hand written in Crimson Editor.
      That, combined with my horrible spelling &amp; grammar, will lead to
      various errors in the document.

    The parser was designed with several specific concepts/features in mind
      <a name="port"><b>Portable:</b></a>  -  <a href="#top">Top of Page</a>
        Portability is one of the main concepts that I spent a lot of time
          on. If the platform you are compiling on supports ANSI C with
          stdio.h, stdlib.h, string.h, and limits.h support, the library
          should compile without any issues.

        This library (v 8.9) has even been tested and found to work
          correctly on the Nintendo Wii with minimum modifications
          (File I/O is different, due to the DVD drive).

        In order to ensure portability, the  Parser was tested on a
          Windows and a Linux machine. Unfortunately, I don't have access
          to a Mac development box, so I'm forced to make do. Since the
          parser does not require any GUI, I was able to rely on strict
          ANSI C (C89). Multiple compilers are used and tested as follows

          Windows:
            MS Compiler       cl  *.c /W4
            GNU               gcc *.c -Wall -Wextra -ansi -pedantic
                              gcc *.c -Wall -Wextra -ansi -pedantic -mno-cygwin
                              g++ *.c -Wall -Wextra -ansi -pedantic
            Borland Compiler  bcc -w *.c
            Digital Mars      dmc file.c -A
            Intel Complier    icl *.c /W3

          Linux:
            GNU               gcc *.c -Wall -Wextra -ansi -pedantic
                              g++ *.c -Wall -Wextra -ansi -pedantic

          For each compiler, the maximum warning level is turned on.
            No warnings or errors are acceptable for a release version.
            The only exception to this policy lies with the Microsoft
            Compiler. /Wall is the maximum; however, this generates warnings
            from the Microsoft headers (none are from Parser.h or Parser.c).

      <a name="noco"><b>No Conditional Compilation:</b></a>  -  <a href="#top">Top of Page</a>
        Conditional compilation (#ifdef &amp; such) is avoided as much as
          possible. Conditional compilation is only used for standard header
          guards and nothing else. In other words, you do not have to add any
          defines to build script or similar to get the Parser to compile.

       <a name="simp"><b>Simple To Use:</b></a>  -  <a href="#top">Top of Page</a>
         To make the library as simple to use as possible, several
           conventions are followed. Firstly, all the function names and
           such follow my coding standards (included). Other then that,
           all of the code is in two files, a .c and an .h. I find it far
           simpler to just copy two files into your project, and then
           included one file (#include "Parser.h", by default) to get the
           library to work with other code. No defines or special
           compilation flags are required.

         In order to increase the simplicity, a file handler was built into
           the project. Personally, I find manual file I/O to be rather ugly
           and fairly inefficient. As such, the Parser provides a
           comprehensive and fairly robust built in File I/O system, to
           automate the process.

       <a name="noob"><b>No Obscure Data Types:</b></a>  -  <a href="#top">Top of Page</a>
         No defined or typedef types beyond the remove of the "struct"
           keyword is used. This should make it obvious as to what type
           of data each variable takes.

         Note: The function callback type is typedef; however, this is only
                 provided to simplify casting procedure. It is explicitly
                 defined everywhere else.

       <a name="noma"><b>No Obscure Macros:</b></a>  -  <a href="#top">Top of Page</a>
         Yes, macros can be really helpful; however, they add another level
           of obscurity to your code. There are no macros used at the
           public level; however, a tiny number of internal macros are used.
           Any macro that is used must be understood by its defined name.

       <a name="docu"><b>Documented:</b></a>  -  <a href="#top">Top of Page</a>
         To improve you understanding of the project, documentation is
           added to the project. Every function has a function header and
           there is a file header in every file. Comments are added to the
           code; however, worthless comments are avoided as much as
           possible.

         The external documentation provided with the project is not
           automatically generated by some program like Doxygen or
           similar. While these tools can be nice, they do no tell you
           anything that reading the code won't tell you, and are thus
           less helpful then a manually authored document. As such, a
           compressive document written in one of the most commonly
           accessed document types is provided.

       <a name="nota"><b>No Tabs:</b></a>  -  <a href="#top">Top of Page</a>
         Tabs are evil. Rather, tabs mixed with spaces are evil. While tabs
           may bet set to 4 spaces in one program, they may bet set to x
           spaces in another program or on another computer. This destroys
           the alignment and code flow, so they are all removed.

         Unfortunately, this does increase the file size.

       <a name="bloc"><b>Block Formatting/Alignment:</b></a>  -  <a href="#top">Top of Page</a>
         I tend to be an alignment whore. I find it far easier to look at
           and read code if it is separated into blocks.

       <a name="dyna"><b>Dynamic, Fast, and Safe:</b></a>  -  <a href="#top">Top of Page</a>
         The library was designed to be as dynamic as possible, without
           sacrificing a huge number of cycles. All code is benchmarked, and
           weight against the usefulness of the feature. If the feature
           eats up a huge number of cycles while not being very useful, it
           will not be implemented.

         To ensure that the Parser is safe, a few cycles are spent on error
           checking. All allocated memory is checked to ensure that it is
           valid (not null), and buffer under/over read is checked. To
           check for any memory related issues, Valgrind and my own memory
           manager is used to check for any issues and memory leaks. No
           memory leaks are tolerated. The memory checking mechanism is
           removed for release.

         That being said, it is still possible to crash the program through
           the parser. If you pass in a pointer to a bad chunk of memory,
           the parser will most probably crash.

       <a name="acom"><b>A Complete Package in one File:</b></a>  -  <a href="#top">Top of Page</a>
         The parser does not depend on any other libraries, other then the
           standard C library. Namely, stdio.h, stdlib.h, string.h, and
           limits.h.

       <a name="tfos"><b>Truly Free - Public Domain</b></a>  -  <a href="#top">Top of Page</a>
         This library is released to the public domain. You are free to do
           anything you want with it.

    <a name="wdiff"><b>How is this Parser different?</b></a>  -  <a href="#top">Top of Page</a>
      The  Parser was not designed to conform to traditional parser
        designs. Generally, the differences can be summed up as follows:

         Parser vs Traditonal Parser:
          Modifiable at runtime
          Built in dynamic lexical analyzer
          Smart built In File I/O
          No required external scripting
          Easy to iterate with
          Built in state system

      Traditional parsers are generally made through a parser generator.
        This alone can make integration and rapid iteration extremely
        difficult to incorporate into a larger project. As such, the
        Parser is built and modifiable at runtime. On top of this, a
        C/C++ interface is provided in order to allow for easy integration
        into an existing project, rather then writing a script to generate
        a .c file, which then may require some additional modifications to
        fully integrate said .c file into your project.

      Along with this, all traditional parsers I've seen have only been
        designed to run as one instance. As such, the Parser is wrapped up
        in a fairly easy to manage state system, to allow multiple
        Parser to exist at one time.

      With that being said, there are plans to expand the Parser to
        incorporate some more traditional parser technologies such as
        BNF style scripts and LALR generation, which again, will be
        done at runtime.



<div align="center"><a name="2.0"><font color="blue"><b>2.0 - Features</b></font></a>  -  <a href="#top">Top of Page</a></div>
<a name="2.01"><font color="blue"><b>2.01 - File Handling</b></font></a>  -  <a href="#top">Top of Page</a>
  A built in file handling system is implemented in the parser. The file
    handling system includes a file fragmentation/caching system. When
    <a href="#4.1.24">ParserInit</a>(&lt;file&gt;, &lt;bufsize&gt;) is called, a buffer size is specified.
    When the data is read in from the file, the specified buffer size determines
    how many bytes to read in from the file.

  Since a token separator can fall on the ends of the data read in, the parser
    accounts for this fragmentation. For example, take

    bufsize - 3
    data    - <font color="purple">"0123456789ABCDEF"</font>

    With a bufsize of 3, the parser will fragment the file into
    Fragment 1 - <font color="purple">"012"</font>
    Fragment 2 - <font color="purple">"345"</font>
    Fragment 3 - <font color="purple">"678"</font>
    Fragment 4 - <font color="purple">"90A"</font>
    Fragment 5 - <font color="purple">"BCD"</font>
    Fragment 6 - <font color="purple">"EF"</font>

  If a token separator was declared as <font color="purple">"234"</font>, it would not be detected, since
    the entire string would never be in the input buffer.

  To handle this, the buffer size is expanded to the length of the longest
    token separator - 1. IE, if <font color="purple">"234"</font> was the only separator, then the
    buffer size would be expanded by 2 (Length(<font color="purple">"234"</font>) - 1).

    Original Buffer:
     -- -- --
    |  |  |  |
     -- -- --

    Expanded:
     -- -- -- -- --
    |  |  |  |  |  |
     -- -- -- -- --

    Note: A null terminator is attached as well, but it is not represented.

  When the data is actually read in, last longest sep - 1 is are attached
    to the front of the buffer. This ensures that all the characters are
    checked against all the possible token separators.

    bufsize     - 3
    Longest Sep - 3
    Actual buf  - 5 (plus a null terminator, so it's actually 6 bytes)
    data        - <font color="purple">"0123456789ABCDEF"</font>

    Fragment 1 - <font color="purple">"012"</font>
    Fragment 2 - <font color="purple">"12345"</font>
    Fragment 3 - <font color="purple">"45678"</font>
    Fragment 4 - <font color="purple">"7890A"</font>
    Fragment 5 - <font color="purple">"0ABCD"</font>
    Fragment 6 - <font color="purple">"CDEF"</font>

  This does force some redundant checking; however, it is far more important
    that the parser correctly locates the tokens.

  If performance is an issue, a low number of short token separators with a
    larger buffer size will greatly increase performance. Larger buffer sizes
    decrease the number of reads from the hard drive; however, the memory
    footprint of the parser will increase. The smallest possible memory
    footprint can be achieved by setting the buffer size to 1; however, it is
    far slower. A buffer size of 1024 bytes (1 KB) is recommended for general
    purposes.

<a name="2.02"><font color="blue"><b>2.02 - Tokens &amp; Token Sets</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Token Separators:</b>
  The actual parsing syntax of the parser is defined as "Token Separators".
    There are several tokenizers on the market (including one in string.h) that
    are fast; however, a single character is not always enough to make parsing
    a file simple and easy. As such, full strings are used and scanned for. I
    refer to the "delimiters" as "Token Separators", since addition logic
    can be attached to them. This library is call a parser, instead of a
    tokienizer, due to this addition logic. Not to mention, that function
    callbacks are supported as well.

  The order the tokens are added does matter. A token added before another
    token will have a higher priority.

  The Token Separators can have the following logic attached to them via
    <a href="#4.1.02">AddTokenSeparator</a>(&lt;token&gt;, &lt;Return&gt;, &lt;switchto&gt;, &lt;ignore&gt;, &lt;fun&gt;, &lt;params&gt;)

    <a name="Return"><b>Return</b></a>   - Should the token be returned when <a href="#4.1.17">GrabToken()</a> is called? If this
                 argument is set to true (1), the token will be returned. If
                 it's set to false (0), the token will not be returned. This is
                 extremely useful to filter out unneeded tokens.
                 For example,

                 data - <font color="purple">"foo  bar"</font> <font color="green">/* Notice the two space between foo &amp; bar */</font>

                 if the Separator is a space, and return is set to 1, namely
                   <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">" "</font>, 1, ...);

                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns "foo" */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns " "   */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns " "   */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns "bar" */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns 0 - End of the data was reached */</font>

                 If return is set to 0, namely
                   <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">" "</font>, 0, ...);

                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns "foo" */</font>
                              <font color="green">/* Both of the spaces are not returned!    */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns "bar" */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns 0 - End of the data was reached */</font>

    <a name="switchto"><b>switchto</b></a> - Should the active token set be changed, when the sep is found?
                 Setting this parameter to -1 disables this feature. If it's
                 set to anything else, the token set will automatically be
                 changed to the specified token set, if it exists.

               Two defines can also be passed to this variable:
                         Define           Value           Description
                 PARSER_TSET_DONT_SWITCH - -1 - Don't change the current TSet
                 PARSER_TSET_LAST        - -2 - Switch to the last active TSet

               <a href="#tsets">See Token Sets</a>

    <a name="ignore"><b>ignore</b></a>   - Should the token separator be ignored? This logic was originally
                 designed to be used when parsing strings.
                 For Example:

                 string - <font color="purple">"foo\"bar"</font>  <font color="green">/* Start and end quotation marks are part
                                       *   of the string                      */</font>

                 Token Sep is a quotation mark, namely
                   <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\""</font>, 1, -1, 0, ...);

                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns quotation mark */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns "foo\\"        */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns quotation mark */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns "bar"          */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns quotation mark */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns 0 - End of the data was reached */</font>

                 If you had wanted to preserve the string, you probably didn't
                   want the parser to pick out the quotation mark from \". To
                   fix this, add another token sep (\") with ignore set to 1

                 <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\""</font>,   1, -1, 0, 0, 0); <font color="green">/* "            */</font>
                 <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\\\""</font>, 0, -1, 1, 0, 0); <font color="green">/* \"           */</font>
                                                  ^- Ignore

                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns quotation mark */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns "foo\"bar"     */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns quotation mark */</font>
                 <a href="#4.1.17">GrabToken()</a>; <font color="green">/* Returns 0 - End of the data was reached */</font>

               Ignore is also useful when combined with a function callback.
                 For example, say you wanted to count all the new lines (\n) in
                 a file. You could set ignore to 1, and then set the function
                 pointer to a function that would increment a global variable
                 that counts the number of new lines. When <a href="#4.1.17">GrabToken</a>() is
                 called, It'll call the callback function when ever it runs into
                 a new line. Since Ignore is set to one, it'll continue to do
                 this until it gets to the end of the file. From there, it'll
                 return the entire file, but you'll have the total number of
                 new lines in the file

               Note: You cannot call <a href="#4.1.17">GrabToken</a>() or similar from a callback with
                       ignore set to 1 (true).
<a name="program1"></a>
                 <font color="green">/*************************************************************
                  * Full Program - Retrieves the number of new lines from a file
                  *                                                           *
                  * Note: You must change &lt;any file&gt; in ParserInit() to the   *
                  *         name of the file you want to get the number of    *
                  *         new lines from.                                   *
                  *************************************************************/</font>
                 <font color="blue">#include</font> <font color="purple">"Parser.h"</font>
                 <font color="blue">#include</font> &lt;stdlib.h&gt; <font color="green">/* free()   */</font>
                 <font color="blue">#include</font> &lt;stdio.h&gt;  <font color="green">/* printf() */</font>

                 <font color="blue">char</font> *NewLineCounter(<font color="blue">char</font> *str, <font color="blue">int</font> *newlines);

                 <font color="blue">int</font> main(<font color="blue">void</font>)
                 {
                   <font color="blue">int</font> NewLines = 1;
                   <a href="#4.1.24">ParserInit</a>(&lt;any file&gt;, 1024);
                   <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\n"</font>, 0, -1, 1, (PCBACK)NewLineCounter,
                                                     &amp;NewLines);

                   free(<a href="#4.1.17">GrabToken()</a>); <font color="green">/* Scan the whole file, and free what   *
                                       * ever is returned                     */</font>

                   printf(<font color="purple">"New Lines: %d\n"</font>, NewLines);

                   <a href="#4.1.21">ParserDeInit()</a>;

                   <font color="blue">return</font> 0;
                 }

                 <font color="blue">char</font> *NewLineCounter(<font color="blue">char</font> *str, <font color="blue">int</font> *newlines)
                 {
                   (*newlines)++;

                   <font color="blue">return</font> str;
                 }<font color="green">
                 /*************************************************************
                  * End of the program                                        *
                  *************************************************************/</font>

    <a name="fun"><b>fun</b></a>      - Function to call when ever a token is found. The prototype for
                 the function is
                   <font color="blue">char</font> *&lt;function name&gt;(<font color="blue">char</font> *str, <font color="blue">void</font> *params);

                 The return of the function should be:
                   0  - Continue the search.
                   1+ - Any string. By default, the safest thing to do is to
                          return str; (first parameter of the function). Any
                          string returned by the callback is assumed to be
                          owned by the parser. As such, it must be allocated by
                          malloc(), calloc(), or realloc(). This enables you to
                          replace any token separator with another string.

                 It is assumed that you own the str parameter. IE, if you do not
                   plan to return the variable, and it is not 0/NULL, you should
                   call free(str);.

                 In the above program, if you changed the ignore parameter to
                   a 0 (false), str will be 0/NULL.

    <a name="params"><b>params</b></a>   - Parameters to pass to the callback. Check <a href="#program1">New Line Counter</a>
                 for an example on how to use this. Once a token separator is
                 found and returned, you can retrieve this variable by calling
                 <a href="#4.1.08">GetParams</a>().

  To add a new Token Separator, you can call two different functions
    <a href="#4.1.01">AddTokenSep()</a>;      - Basic version that attaches default behavior
    <a href="#4.1.02">AddTokenSepataor()</a>; - Advanced version that allows you to define the logic.

    To use <a href="#4.1.01">AddTokenSep()</a>, you only have to pass in a pointer to a string. A 1+
      will be returned if a error occurred and a 0 will be returned if the token
      was added.

      Default behavior:
        Return   -  1 - Return the token when <a href="#4.1.17">GrabToken()</a> is called.
        switchto - -1 - Don't change the token set.
        ignore   -  0 - Don't ignore the token separator.
        fun      -  0 - Don't call a function.
        params   -  0 - No params to pass to the callback

    <a href="#4.1.02">AddTokenSepataor()</a> allows you specify the logic of the token separator.

  <a name="tsets"><b>Token Sets:</b></a>
    To allow the  Parser to be more dynamic, multiple Token Sets can be
      defined. A "Token Set" is just a set of tokens. Each token set is
      completely separated from one another. This allows the parser to switch
      the parsing syntax at runtime.

    Once the parser is initialized (by calling <a href="#4.1.24">ParserInit()</a>), the initial token
      set will automatically be created, and set as the active token set. The
      initial token set has an index of 0.

    To create a new token set, simply call
    <a href="#4.1.03">AddTokenSet()</a>;

    The function will create a new token set, set the new token set as the
      active token set, and then return the index of the token set. To properly
      handle the return value, you should create a descriptive variable to
      store the index.
      For Example:

      <a href="#4.1.24">ParserInit</a>(0, 1024);              <font color="green">/*Set up parser and create token set 0*/</font>
      <font color="blue">int</font> tset_comments = <a href="#4.1.03">AddTokenSet()</a>;<font color="green">/* Create tset that handles comments  */</font>
      <font color="blue">int</font> tset_strings  = <a href="#4.1.03">AddTokenSet()</a>;<font color="green">/* Create tset that handles strings   */</font>

    Likewise, you can also get the current token set by calling:
      <a href="#4.1.10">GetTokenSet</a>();

    While this is the proper way to handle token set indexes, feel free to just
      hard code the value. The initial token set is 0. Each call to
      <a href="#4.1.03">AddTokenSet</a>() will increase the index by 1. IE, tset_comments will be 1,
      and tset_strings will be set to 2.

    All calls to <a href="#4.1.01">AddTokenSep()</a>, <a href="#4.1.02">AddTokenSeparator()</a>, <a href="#4.1.17">GrabToken()</a>, <a href="#4.1.28">PeekToken()</a>,
      etc will use the active token set.

    To Change the active token set, simply call <a href="#4.1.35">SetTokenSet()</a>;

    <a href="#4.1.35">SetTokenSet</a>(tset_comments); <font color="green">/* Set the active token set to handle comments*/</font>
    <a href="#4.1.35">SetTokenSet</a>(tset_strings);  <font color="green">/* Set the active token set to handle strings */</font>
    <a href="#4.1.35">SetTokenSet</a>(0);             <font color="green">/* Set the active tset to the initial tset   */</font>

    <a href="#4.1.35">SetTokenSet</a>() will return a -1 if the token set index you specified is
      invalid, Otherwise, <a href="#4.1.35">SetTokenSet</a>() will return the index you passed in.

    To add further automation to the parser, you can specify which token set
      the parser will use when ever a token separator is located. To do this,
      specify the token set the parser should switch to, as the switchto
      parameter.

      For example, let's write a program that will print only the C style
        comments and strings from Parser.c. First, we Initialize the Parser.
        That will create the initial token set (0) that will handle all the
        switching between token sets, and calling the proper function. Once the
        initial token set is created, create two addition token sets. The first
        token set will handle all the strings. The 2nd, will handle all the
        comments. Once we have all the token sets, we switch back to the
        initial token set, otherwise we would add the token separators to the
        last created token set.

      Now that the initial token set is active, and all the addition token
        sets have been created, we can start adding the parsing syntax.

        Initial Token Set:
          <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\""</font>, 0, tset_strings,  0, PrintString, 0);
            "  - Return   - 0            - Don't return it
                 switchto - tset_strings - switch to tset that handles strings
                 ignore   - 0            - Don't ignore the token.
                 fun      - PrintString  - Print the string to the screen
                 params   - 0            - Don't pass any parameters

          <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"/*"</font>, 0, tset_comments, 0, PrintComment, 0);
            /* - Return   - 0            - Don't return it
                 switchto - tset_comments- switch to tset that handles comments
                 ignore   - 0            - Don't ignore the token
                 fun      - PrintComment - Print comment to command prompt
                 params   - 0            - Don't pass any parameters

        With the initial token set up, we need to set up the two additional
          token sets.

        <a href="#4.1.35">SetTokenSet</a>(tset_strings);

        tset_strings:
          <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\\\\"</font>, 0, -1, 1, 0, 0);
            \\ - Return   -  0 - Don't return it
                 switchto - -1 - Don't change the current token set
                 ignore   -  1 - Ignore the token, so we don't break up strings
                 fun      -  0 - Don't call any function
                 params   -  0 - Don't pass any parameters

          <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\\\""</font>, 0, -1, 1, 0, 0);
            \" - Return   -  0 - Don't return it
                 switchto - -1 - Don't change the current token set
                 ignore   -  1 - Ignore the token, so we don't break up strings
                 fun      -  0 - Don't call any function
                 params   -  0 - Don't pass any parameters

          <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\""</font>,   0,  0, 0, 0, 0);
            "  - Return   -  0 - Don't return it
                 switchto -  0 - Switch to the initial token set
                 ignore   -  0 - Don't ignore it
                 fun      -  0 - Don't call a function
                 params   -  0 - Don't pass any parameters

        <a href="#4.1.35">SetTokenSet</a>(tset_comments);

        tset_comments:
          <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"*/"</font>, 0, 0, 0, 0, 0);
            */ - Return   -  0 - Don't return it
                 switchto -  0 - Switch to the initial token set
                 ignore   -  0 - Don't ignore it
                 fun      -  0 - Don't call a function
                 params   -  0 - Don't pass any parameters

        With all the token sets set up, we need to switch back to the initial
          token set before we can start parsing the file.

        <a href="#4.1.35">SetTokenSet</a>(0);

        With every thing set up, the actual parsing is fairly automatic.

        When <a href="#4.1.17">GrabToken()</a> is called, It'll first scan the file for a separator.
          If it finds a /*, it'll switch to tset_comments, and then call the
          function PrintComment(). In PrintComment(), a printf() is called
          along with another <a href="#4.1.17">GrabToken()</a>. In PrintComment(), <a href="#4.1.17">GrabToken()</a> will
          return everything up to the */. Once */ is found, the token set
          will automatically be switched back to the initial token set, and
          then continue to search for another token. The same procedure happens
          for strings as well.
<font color="green"><a name="program2"></a>
      /************************************************************************
       * Start of Program. Prints out all comments and strings from Parser.c  *
       ************************************************************************/</font>
      <font color="blue">#include</font> <font color="purple">"Parser.h"</font>
      <font color="blue">#include</font> &lt;stdio.h&gt;    <font color="green">/* printf()         */</font>
      <font color="blue">#include</font> &lt;stdlib.h&gt;   <font color="green">/* *alloc(), free() */</font>

      <font color="blue">char</font> *PrintString (<font color="blue">char</font> *str, <font color="blue">void</font> *);
      <font color="blue">char</font> *PrintComment(<font color="blue">char</font> *str, <font color="blue">void</font> *);

      <font color="blue">int</font> main(<font color="blue">void</font>)
      {
        <font color="blue">int</font>   tset_strings;
        <font color="blue">int</font>   tset_comments;
        <font color="blue">char</font> *buffer;

        <a href="#4.1.24">ParserInit</a>(<font color="purple">"Parser.c"</font>, 1024);

        tset_strings  = <a href="#4.1.03">AddTokenSet</a>();
        tset_comments = <a href="#4.1.03">AddTokenSet</a>();

        <a href="#4.1.35">SetTokenSet</a>(0);
        <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\""</font>, 0, tset_strings,  0, PrintString , 0);
        <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"/*"</font>, 0, tset_comments, 0, PrintComment, 0);

          <font color="green">/* Set up the token set that will handle the strings.               *
           * Note: We need to ignore \\ as well as \", since it is possible to*
           *         have something like this \\". If we don't ignore \\, then*
           *         the parser will continue to search for a " since \" will *
           *         be picked out of the stream.                             */</font>
        <a href="#4.1.35">SetTokenSet</a>(tset_strings);
        <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\\\\"</font>, 0, -1, 1, 0, 0);
        <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\\\""</font>, 0, -1, 1, 0, 0);
        <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"\""</font>,   0,  0, 0, 0, 0);

          <font color="green">/* Set up the token set that will handle all comments */</font>
        <a href="#4.1.35">SetTokenSet</a>(tset_comments);
        <a href="#4.1.02">AddTokenSeparator</a>(<font color="purple">"*/"</font>, 0, 0, 0, 0, 0);

        <a href="#4.1.35">SetTokenSet</a>(0);
<font color="green">
          /* Loop through all the code. <a href="#4.1.17">GrabToken()</a> will return chunks of code*
           *   so, we need to free it until we get a null buffer/end of file  */</font>
        <font color="blue">for</font>(buffer = <a href="#4.1.17">GrabToken()</a>; buffer; buffer = <a href="#4.1.17">GrabToken()</a>);
          free(buffer);

          <font color="green">/* Clean up the parser */</font>
        <a href="#4.1.21">ParserDeInit</a>();

        <font color="blue">return</font> 0;
      }

      <font color="blue">char</font> *PrintString (<font color="blue">char</font> *str, <font color="blue">void</font> *a)
      {
        <font color="blue">char</font> *buffer = <a href="#4.1.17">GrabToken()</a>;
        printf(<font color="purple">"String Found!\n\"%s\"\n\n"</font>, buffer);
        free(buffer);

          <font color="green">/* We own str, so free it if it's valid */</font>
        <font color="blue">if</font>(str)
          free(str);

        <font color="blue">return</font> 0;  <font color="green">/* Continue Searching */</font>
      }

      <font color="blue">char</font> *PrintComment(<font color="blue">char</font> *str, <font color="blue">void</font> *a)
      {
        <font color="blue">char</font> *buffer = <a href="#4.1.17">GrabToken()</a>;
        printf(<font color="purple">"Comment Found!\n/*%s*/\n\n"</font>, buffer);
        free(buffer);

          <font color="green">/* We own str, so free it if it's valid */</font>
        <font color="blue">if</font>(str)
          free(str);

        <font color="blue">return</font> 0;  <font color="green">/* Continue Searching */</font>
      }<font color="green">
      /************************************************************************
       * End of Program                                                       *
       ************************************************************************/</font>

<a name="2.03"><font color="blue"><b>2.03 - Text Mode Functions</b></font></a>  -  <a href="#top">Top of Page</a>
  <a href="#4.1.17">GrabToken()</a> and <a href="#4.1.28">PeekToken()</a> are the main text file functions. They search
    through the file for a Token Separator and return a pointer to a null
    terminated array. These functions will work with binary files as well;
    however, due to NULL terminator, using these functions will cause all
    tokens that start with a 0 to be ignored.

    <a href="#4.1.16">GrabInt()</a> and <a href="#4.1.15">GrabFloat()</a> utilize <a href="#4.1.17">GrabToken()</a>, the conversion into the
    respective variable type.

    NOTE: Unicode is not supported.

  Text Mode Compliant Functions:
    <a href="#4.1.17">GrabToken()</a>;
    <a href="#4.1.28">PeekToken()</a>;
    <a href="#4.1.16">GrabInt  ()</a>;
    <a href="#4.1.15">GrabFloat()</a>;
    <a href="#4.1.32">Seek     ()</a>;

<a name="2.04"><font color="blue"><b>2.04 - Binary Mode Functions</b></font></a>  -  <a href="#top">Top of Page</a>
  <a href="#4.1.32">Seek()</a> is the main driving force behind binary mode. It allows you to
    scan the file, until you get to the position you want. <a href="#4.1.12">GrabBinaryInt()</a>,
    <a href="#4.1.11">GrabBinaryFloat()</a>, <a href="#4.1.13">GrabByte()</a>, and <a href="#4.1.14">GrabBytes()</a> allow you to retrieve the
    data. You can use <a href="#4.1.17">Grab</a>/<a href="#4.1.28">PeekToken</a>; however, binary data might be
    interpreted to match a token separator.

  Binary Mode Compliant Functions:
    <a href="#4.1.32">Seek           ()</a>;
    <a href="#4.1.12">GrabBinaryInt  ()</a>;
    <a href="#4.1.11">GrabBinaryFloat()</a>;
    <a href="#4.1.14">GrabBytes      ()</a>;
    <a href="#4.1.13">GrabByte       ()</a>;
    <a href="#4.1.27">PeekByte       ()</a>;

<a name="2.05"><font color="blue"><b>2.05 - Function Callbacks</b></font></a>  -  <a href="#top">Top of Page</a>
  The parser supports callback functions. The prototype for the function is
     <font color="blue">char</font> *&lt;function name&gt;(<font color="blue">char</font> *str, <font color="blue">void</font> *params);

   The return of the function should be:
     0  - Continue the search.
     1+ - Any string. By default, the safest thing to do is to return str;
           (first parameter of the function). Any string returned by the
           callback is assumed to be owned by the parser. As such, it must be
           allocated by malloc(), calloc(), or realloc(). This enables you to
           replace any token separator with another string.

   It is assumed that you own the str parameter. IE, if you do not plan to
     return the variable, and it is not 0/NULL, you should call free(str);.

   See The following for examples:
     <a href="#program1">Sample Program: New Line Counter</a>
     <a href="#program2">Sample Program: Print comments and Strings</a>

<a name="2.06"><font color="blue"><b>2.06 - String Manipulation Functions</b></font></a>  -  <a href="#top">Top of Page</a>
  <a href="#4.2.01">RemoveWhiteSpaces()</a> - Removes all white spaces from a string (Space, New Line,
                          Carriage Return, and Tab)
  <a href="#4.2.02">ToUpper     ()</a> - Converts all letters in a string to upper case
  <a href="#4.2.03">ToLower     ()</a> - Converts all letters in a string to lower case
  <a href="#4.2.04">Dup         ()</a> - Creates a copy of the specified string
  <a href="#4.2.05">DupLen      ()</a> - Same as above, but takes the length
  <a href="#4.2.06">DupRange    ()</a> - Creates a copy of a specific part of a string
  <a href="#4.2.07">DupRangeFile()</a> - Creates a copy of a specific part of a file
  <a href="#4.2.08">Cmp         ()</a> - Compares two strings. If they are equal, 1 is returned. If
                     not, 0 is returned.

<a name="2.07"><font color="blue"><b>2.07 - Options/Configuration</b></font></a>  -  <a href="#top">Top of Page</a>
  The Parser contains several runtime definable options. Options can be
    enabled, disable, or checked with the following functions:
      <a href="#4.1.23">ParserEnable   ()</a> - Enables a option/feature
      <a href="#4.1.22">ParserDisable  ()</a> - Disables a option/feature
      <a href="#4.1.25">ParserIsEnabled()</a> - Checks to see if all the specified options are enabled

    All the above functions can take multiple options at the same time.
      For Example,
        <a href="#4.1.23">ParserEnable</a>(PARSER_GLOBBING | PARSER_HASH | PARSER_CASE_INSENSITIVE);

    <b>Search Algorithm Options:</b>
      PARSER_CASE_INSENSITIVE    - All search related functions will perform
                                     case insensitive searches.

      PARSER_WILDCARD            - Globbing based searches will be enabled.
                                     Namely, the * character will be use to
                                     accept any number of additional characters.
                                   This feature will be disabled if
                                     PARSER_REGEX is enabled.
                                   See <a href="#glob">Globbing</a> for more info.

      PARSER_GLOBBING            - Same as PARSER_WILDCARD

      PARSER_REGULAR_EXPRESSIONS - Enables RegEx searching syntax.
                                   This feature will take precedence over and
                                     disable the following features:
                                       PARSER_HASH
                                       PARSER_WILDCARD
                                       PARSER_GLOBBING
                                       PARSER_SORT_TOKEN_SEPS
                                   See <a href="#regex">RegEx</a> for more info.

      PARSER_REGEX               - Same as PARSER_REGULAR_EXPRESSIONS

    <b>Performance Options:</b>
      PARSER_HASH                - Hashes the first character of each token
                                     separator. This can drastically speed up
                                     the parsing process, in exchange for
                                     additional memory usage.
                                   This feature will be disabled if
                                     PARSER_REGEX is enabled.
                                   This feature implies PARSER_SORT_TOKEN_SEPS

      PARSER_CLOSE_FILE          - Closes the file after it is read from. By
                                     default, the file is left open due to
                                     performance reasons. Namely, if the file
                                     is closed, the OS will have to seek to
                                     the correct location in the file which
                                     tends to be very expensive.
                                   Closing a file will reduce the total number
                                     of active system file handles, in exchange
                                     for a drastic performance loss.

      PARSER_SORT_TOKEN_SEPS     - Performs a week sorting algorithm to all
                                     token separators. This guarantees that
                                     all supersets of token separators will be
                                     check before any subsets, in exchange for
                                     a slightly longer initialization time.
                                   This feature will be disabled if
                                     PARSER_REGEX is enabled.

    <b>Memory Options:</b>
      PARSER_CONST_FILE_NAME     - It is assumed that file name passed to
                                     <a href="#4.1.18">LoadFile</a>() or <a href="#4.1.24">ParserInit</a>() is const. As
                                     such, the string will not be duplicated,
                                     nor will it be freed when <a href="#4.1.21">ParserDeInit</a>() is
                                     called. As such, the string must be valid
                                     for the entire life of the parser.

      PARSER_CONST_LOAD_MEMORY   - It is assumed that memory passed to
                                     <a href="#4.1.19">LoadMemory</a>() or <a href="#4.1.20">LoadMemoryLen</a>() is const.
                                     As such, the memory will not be duplicated,
                                     nor will it be freed when <a href="#4.1.21">ParserDeInit</a>() is
                                     called. As such, the memory must be valid
                                     for the entire life of the parser.

      PARSER_CONST_TOKEN_SEPS    - It is assumed that token separator passed to
                                     <a href="#4.1.02">AddTokenSeparator</a>() is const.
                                     As such, the string will not be duplicated,
                                     nor will it be freed when <a href="#4.1.21">ParserDeInit</a>() is
                                     called. As such, the string must be valid
                                     for the entire life of the parser.

      PARSER_OWNS_FILE_NAME      - It is assumed that the parser owns the
                                     pointer passed to <a href="#4.1.18">LoadFile</a>() and
                                     <a href="#4.1.24">ParserInit</a>(). As such, the pointer
                                     will be freed when <a href="#4.1.21">ParserDeInit</a>()
                                     is called. The pointer must be allocated
                                     with malloc(), calloc(), or realloc().

      PARSER_OWNS_LOAD_MEMORY    - It is assumed that the parser owns the
                                     pointer passed to <a href="#4.1.19">LoadMemory</a>() and
                                      <a href="#4.1.20">LoadMemoryLen</a>(). As such, the pointer
                                     will be freed when <a href="#4.1.21">ParserDeInit</a>()
                                     is called. The pointer must be allocated
                                     with malloc(), calloc(), or realloc().

      PARSER_OWNS_TOKEN_SEPS     - It is assumed that the parser owns the
                                     pointer passed to <a href="#4.1.02">AddTokenSeparator</a>(). As
                                     such, the pointer will be freed when
                                     <a href="#4.1.21">ParserDeInit</a>() is called. The pointer must
                                     be allocated with malloc(), calloc(), or
                                     realloc().

<a name="2.08"><font color="blue"><b>2.08 - Search Methods</b></font></a>  -  <a href="#top">Top of Page</a>
  The following search algorithms directly effect how a token separator is
    interpreted by the Parser. The more complex the search algorithm, the slower
    it tends to be.

  <a name="lin"><b>Linear:</b></a>
    This is the default and fastest search algorithm within the Parser. Simply
      stated, a linear search is performed on the file/memory. IE, the Parser
      will start from the first byte and compare it against all the token
      separators. If none of the separators match, the next byte will be
      tested, and so on.

    In this mode, the token separators will be literally interpreted. IE, there
      are no reserved characters, other then the NULL terminator/0.

    To ensure that a linear search is performed, call:
      <a href="#4.1.22">ParserDisable</a>(PARSER_GLOBBING | PARSER_REGEX);

  <a name="glob"><b>Globbing:</b></a>
    To enable Globbing, call:
      <a href="#4.1.23">ParserEnable</a>(PARSER_GLOBBING);

    Globbing is similar to the linear search method; however, the asterisk (*)
      has a special meaning. Namely, it can be any number of any types of
      any characters. IE,

          Glob          Matching Examples
        foo*bar - foobar, foo\nbar, foo___bar, foo  o  foo  bar
        *foo*   - asdf foo bar, dddfoobar,
        *f*r*   - fr, f r, af r, af rd

          Glob         Non-Matching Examples
        foo*bar - foba, fooba, foob ar, f oobar
        *foo*   - fo o, asf oo
        *f*r*   - afh

    In order to prevent a glob from returning the content of an entire file,
      all the other token separators will be taken into account. This will
      effect the glob if it has a * on the front or end of the token ("*foo*").
      Internal * are not separator delimited ("f*o").

      So, if you have this

        <a href="#4.1.19">LoadMemory</a>(<font color="purple">"ab foo bar ddd"</font>);

        <a href="#4.1.23">ParserEnable</a>(PARSER_GLOBBING);

        <a href="#4.1.01">AddTokenSep</a>(<font color="purple">" "</font>);
        <a href="#4.1.01">AddTokenSep</a>(<font color="purple">"*foo*bar"</font>);

      Then,

        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns "ab"      */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns " "       */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns "foo bar" */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns " "       */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns "ddd"     */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns 0 - End of the data was reached */</font>

      Likewise, with the same Token Set,

        <a href="#4.1.19">LoadMemory</a>(<font color="purple">"ab ddfoo foo baree ddd"</font>);

        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns "ab"      */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns " "       */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns "ddfoo foo baree" */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns " "       */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns "ddd"     */</font>
        <a href="#4.1.17">GrabToken</a>(); <font color="green">/* Returns 0 - End of the data was reached */</font>

    Warning: Once a glob has found the first part of a non wildcard segment of
               the token, it will search to the end of the file/memory in order
               to locate the end. It will break out as soon as an ending segment
               is found. In other words, a O(N^2) search might be performed by
               a glob on a file. IE, with a bad set of data, globbing may be
               extremely slow.

    Warning: There is no way to escape the *. Once enabled, all * will be
               interpreted as a wildcard character.

  <a name="regex"><b>RegEx:</b></a>
    Regular Expressions, or RegEx for short, is a much more powerful version of
      globbing.

    Warning: The RegEx engine is still in development. It is possible to get
              stuck in an infinite loop.

    To enable RegEx, call:
      <a href="#4.1.23">ParserEnable</a>(PARSER_REGEX);

    <a href="http://en.wikipedia.org/wiki/Regular_expression" target="_blank">RegEx on Wikipedia</a>

    Supported Syntax:
      Logic:
        ^ - Start of String      $ - End of String
       \b - Word Boundary       \B - Not a Word Boundary
       \&lt; - Start of Word       \&gt; - End of Word
       |  - Or. Ex, <font color="purple">"a|b"</font> will match <font color="purple">'a'</font> or <font color="purple">'b'</font>
      Ranges:
        [aqf] - Will Match a, q, or f. Anything can be added here
        [^a]  - Anything other then 'a'
        [a-z] - Anything from <font color="purple">'a'</font> to <font color="purple">'z'</font>. <font color="purple">'a'</font> and <font color="purple">'z'</font> can be
                  replaced with any ASCII characters.
      Predefined Ranges:
        \s - [ \t\r\n\v\f] - White Space
        \S - [^\s]         - Not White Space
        \d - [0-9]         - Digit
        \D - [^\d]         - Not a Digit
        \w - [A-Za-z0-9_]  - Word
        \W - [^\w]         - Not a Word
      Quantifiers:
        All Quantifiers are Greedy. Append a <font color="purple">'?'</font> after a
          quantifier to make it non greedy.
        ? - 0 or 1      * - 0 or more
        + - 1 or more
      Other:
        (...) - Sub expressions. Ex, <font color="purple">"(a|b)+"</font> will match
                  <font color="purple">"aaaa"</font>, <font color="purple">"aabb"</font>, <font color="purple">"abab"</font>, <font color="purple">"bbba"</font>, ...

    Internally, all RegEx's in the Parser are compiled into byte code.
      This is done in order to simplify the implementation of the RegEx engine,
      as well to improve the overall performance. Currently, the Parser uses
      a DFA engine, due to their high performance.

    Planned Enhancements:
      Capture Groups
      Backreferences

    Warning: While still usable, RegEx's tend to be slower then Linear and
               Globbing based searches.

<a name="2.09"><font color="blue"><b>2.09 - State Management</b></font></a>  -  <a href="#top">Top of Page</a>
  For simplicity, the Parsers state management is handled through a global
    pointer. This reduces the total number of variables you have to manage.

  If you need more then one Parser state, the following state management
    methods are provided to simplify the overall process.

  <a name="manual"><b>Manual:</b></a>
    When you are manually managing the Parser state, you are responsible for
      keeping track of the state's pointer. Once the Parser is initialized
      via <a href="#4.1.24">ParserInit</a>(), you can get the state pointer by
      calling:

        <font color="blue">void</font> *state = <a href="#4.1.09">GetParserState</a>();

    This will give you a direct copy of the state pointer. The current state
      will still be active.

    To change the active Parser state, call:

      <a href="#4.1.34">SetParserState</a>(state);

    To deinitialize the Parser's state while the state is still active, call

      <a href="#4.1.21">ParserDeInit</a>();

    The main idea behind this mode is to wrap any code that needs to create a
      new parser state with the above function calls.

    For Example (assume foo() was called):

      <font color="blue">void</font> foo(<font color="blue">void</font>)
      {
          <font color="green">/* Preserve any old parser state */</font>
        <font color="blue">void</font> *old_state = <a href="#4.1.09">GetParserState</a>();

          <font color="green">/* Create a new state */</font>
        <a href="#4.1.34">SetParserState</a>(0);
        <a href="#4.1.24">ParserInit</a>(...);

          <font color="green">/* Do stuff with the Parser... */</font>

        bar();

          <font color="green">/* Do stuff with the Parser... */</font>

          <font color="green">/* Cleanup the current state, and restore the old state */</font>
        <a href="#4.1.21">ParserDeInit</a>();
        <a href="#4.1.34">SetParserState</a>(old_state);
      }

      <font color="blue">void</font> bar(<font color="blue">void</font>)
      {
          <font color="green">/* Preserve any old parser state */</font>
        <font color="blue">void</font> *old_state = <a href="#4.1.09">GetParserState</a>();

          <font color="green">/* Create a new state */</font>
        <a href="#4.1.34">SetParserState</a>(0);
        <a href="#4.1.24">ParserInit</a>(...);

          <font color="green">/* Do stuff with the Parser... */</font>

        <a href="#4.1.21">ParserDeInit</a>();
        <a href="#4.1.34">SetParserState</a>(old_state);
      }

    So, looking at the above code, when foo is called, we preserve any Parser
      state that might be active. Then, we create a new state. We then call
      bar() which does the same thing. This guarantees that we will not
      do any harmful things to another parser state.

    Alternatively, we can wrap the call to bar() with <a href="#4.1.09">Get</a>/<a href="#4.1.34">SetParserState</a>();
      however, this tends to be a bit more dangerous and can lead to a lot
      more code (you'll need to do this for all calls to functions that
      expect an empty Parser state).

    The main advantage to this method, is that you can prebuild a set of
      Parsers, and switch to the correct Parser state when needed.

  <a name="stack"><b>Stack:</b></a>
    The Stack (LIFO) based state management is very similar to the <a href="#manual">Manual</a>
      state management; however, it is not as flexible. In exchange for this,
      stack based management tends to be slightly simpler.

    The stack based management revolves around 2 functions:
      <a href="#4.1.31">PushParserState</a>() pushes the current Parser state onto a
        internal global stack, and then sets the current state to 0.

      <a href="#4.1.29">PopParserState</a>() DeInitializes the current Parser state, and
        restores any old state.

    So, the above example would work out to
      <font color="blue">void</font> foo(<font color="blue">void</font>)
      {
          <font color="green">/* Preserve any old parser state */</font>
        <a href="#4.1.31">PushParserState</a>();

          <font color="green">/* Create a new state */</font>
        <a href="#4.1.24">ParserInit</a>(...);

          <font color="green">/* Do stuff with the Parser... */</font>

        bar();

          <font color="green">/* Do stuff with the Parser... */</font>

          <font color="green">/* Cleanup the current state, and restore the old state */</font>
        <a href="#4.1.29">PopParserState</a>();
      }

      <font color="blue">void</font> bar(<font color="blue">void</font>)
      {
          <font color="green">/* Preserve any old parser state */</font>
        <a href="#4.1.31">PushParserState</a>();

          <font color="green">/* Create a new state */</font>
        <a href="#4.1.24">ParserInit</a>(...);

          <font color="green">/* Do stuff with the Parser... */</font>

        <a href="#4.1.29">PopParserState</a>();
      }

    The main advantage to this method is that we do not have to keep track of
      the old state pointer. Plus, this only takes 3 lines of code instead of
      the original 5.

    In exchange for this, we are limited on the total number of states that the
      Parser will keep a track of. By default, the Parser will keep track of
      10 states. The number of states can be increased by modifying
      PARSER_STATE_STACK_SIZE in Parser.c. On top of this, the stack method
      only works in a linear fashion. The manual management can switch to any
      active state, rather then only the last one.

<a name="2.10"><font color="blue"><b>2.10- C++ Wrapper</b></font></a>  -  <a href="#top">Top of Page</a>
  Included with the library is a C++ wrapper. This wrapper is largely just
    copy and paste; however, there are a few differences:

    <b>Differences:</b>
      <a href="#4.1.24">ParserInit</a>()   -&gt; Class Constructor
      <a href="#4.1.21">ParserDeInit</a>() -&gt; Class Destructor
      <a href="#4.1.01">AddTokenSep</a>()  -&gt; Removed. Done through AddTokenSeparator() defaults.

      All Parser*() functions have the "Parser" part removed. IE,
        <a href="#4.1.23">ParserEnable</a>() -&gt; Enable() and similar

      Multiple States handled through C++ classes. IE, no more
        <a href="#4.1.09">Get</a>/<a href="#4.1.34">SetParserState</a>();
        <a href="#4.1.31">Push</a>/<a href="#4.1.29">PopParserState</a>();

      Callbacks are now passed <font color="blue">Parser</font> &amp;. IE,
        <font color="blue">char</font> *&lt;function name&gt;(<font color="blue">Parser</font> &amp;p, <font color="blue">char</font> *str, <font color="blue">void</font> *params);

      Copy constructor is implemented.

    <b>Important things that did not change</b>
      malloc(), calloc(), realloc(), and free() are still used internally. As
        such, all pointers returned by the parser should still be freed with
        free().

      new and delete should only be used on allocate and free the Parser class.

<div align="center"><a name="3.0"><font color="blue"><b>3.0 - Using the Parser</b></font></a>  -  <a href="#top">Top of Page</a></div>
<a name="3.1"><font color="blue"><b>3.1 - Compiling the Parser</b></font></a>  -  <a href="#top">Top of Page</a>
  To compile the parser, simply add Parser.h and Parser.c to your project.
    Add Parser.c to your make file, command line, or what ever. No compile
    time defines or special switches are required.

  Note: If you are working on a C++ project, you might want to rename Parser.c
          to Parser.cpp or use the <a href="#2.10">C++ wrapper</a>.

  The Parser has been compiled and tested with
    Windows:
      MS Compiler       cl  *.c /W4
      GNU               gcc *.c -Wall -Wextra -ansi -pedantic
                        gcc *.c -Wall -Wextra -ansi -pedantic -mno-cygwin
                        g++ *.c -Wall -Wextra -ansi -pedantic
      Borland Compiler  bcc -w *.c
      Digital Mars      dmc file.c -A
      Intel Complier    icl *.c /W3

    Linux:
      GNU               gcc *.c -Wall -Wextra -ansi -pedantic
                        g++ *.c -Wall -Wextra -ansi -pedantic

<a name="3.2"><font color="blue"><b>3.2 - Initialization</b></font></a>  -  <a href="#top">Top of Page</a>
  Before you can use the Parser, you must first call
  <a href="#4.1.24">ParserInit</a>(&lt;file to parse&gt;, &lt;buffer size>);

  After this is done, any options you want should be enabled.
    See <a href="#2.07">Options/Configuration</a>.

<a name="3.3"><font color="blue"><b>3.3 - Setting up the Token Set</b></font></a>  -  <a href="#top">Top of Page</a>
  Once the parser has been initialized, you have to set up the token sets. If
    you are parsing a pure binary file, you do not need to add any token
    separators.

  To add a token separator, call
    <a href="#4.1.01">AddTokenSep</a>(&lt;token&gt;);
    <a href="#4.1.02">AddTokenSeparator</a>(&lt;token&gt;, <a href="#Return">&lt;return&gt;</a>, <a href="#switchto">&lt;switchto&gt;</a>, <a href="#ignore">&lt;ignore&gt;</a>, <a href="#fun">&lt;fun&gt;</a>, <a href="#params">&lt;params&gt;</a>);

  To create a new Token Set, call
    <a href="#4.1.03">AddTokenSet()</a>;

  To change the current token set, call
    <a href="#4.1.35">SetTokenSet</a>(&lt;token set&gt;);

  <a href="#tsets">More on Token Sets</a>

<a name="3.4"><font color="blue"><b>3.4 - Parsing the file</b></font></a>  -  <a href="#top">Top of Page</a>
  Once the token set(s) have been set up, you begin to parse the file.

  <a href="#4.1.17">GrabToken()</a> is the main parser function. When <a href="#4.1.17">GrabToken()</a> is called, it'll
    retrieve the next token from the file. If a 0 (null) is returned, the end
    of the file was reached or an error occurred.

  <a href="#2.03">Text Mode Functions</a>
  <a href="#2.04">Binary Mode Functions</a>

<a name="3.5"><font color="blue"><b>3.5 - Deinitialization</b></font></a>  -  <a href="#top">Top of Page</a>
  Once you are done parsing, you should call
    <a href="#4.1.21">ParserDeInit()</a>;


<div align="center"><a name="4.0"><font color="blue"><b>4.0 - Functions</b></font></a>  -  <a href="#top">Top of Page</a></div>
<div align="center"><a name="4.1"><font color="blue"><b>4.1 - Public Parser Functions</b></font></a>  -  <a href="#top">Top of Page</a></div>
<div align = "center">The following functions are the public interface for interacting
with the Parser.</div>

<a name="4.1.01"><font color="blue"><b>4.1.01 - AddTokenSep()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> AddTokenSep(<font color="blue">const char</font> *sp);

  <b>Description:</b>
    Adds a new token separator to the current token set. This function is an
      adapter for <a href="#4.1.02">AddTokenSeparator()</a>, that uses the default settings.
        Return   -  1 - The token separator will be returned
        switchto - -1 - Don't change the token set
        ignore   -  0 - Don't ignore the token
        fun      -  0 - Don't call a callback function
        params   -  0 - Don't pass any parameters

  <b>Inputs:</b>
    *sp - Pointer to the string to use as a token separator. C style string -
            must be null terminated.

  <b>Output:</b>
    0  - Token has been added to the parser.
    1+ - The specified token is not valid, or another error occurred. This value
           may one or more of the following flags:
             PARSER_TOKEN_NULL          - sp == NULL
             PARSER_OUT_OF_MEMORY       - Could not allocate enough memory to
                                            add the token to parser. This error
                                            will usually cause the rest of the
                                            parser to error out.
             PARSER_REGEX_COMPILE_ERROR - Failed to compile a RegEx to byte code
             PARSER_UNBALANCED_PARENS   - RegEx has unbalanced ()
             PARSER_UNBALANCED_BRACKETS - RegEx has unbalanced []

  <b>Notes:</b>
    The order that tokens are added matters. A token passed in before another
      tokens will be detected first. IE, if you passed in
      AddTokenSep("23");
      AddTokenSep("2");

      "23" will be check for before "2" is checked for.

      This is very useful if you have a token that is a superset of another.

      To change this behavior, call
        <a href="#4.1.23">ParserEnable</a>(PARSER_SORT_TOKEN_SEPS);

      This will cause a weak sorting algorithm to be applied to the tokens
      separator, so that supersets of tokens will always be checked before
      subsets.

    By default, the token that is passed in will be duplicated. To change this
      behavior, call <a href="#4.1.23">ParserEnable</a>(); with one of the
      following defines:

      PARSER_CONST_TOKEN_SEPS - Token is assumed to be constant, and will not
                                  be duplicated or freed. As such, the token
                                  must always be available, for the entire life
                                  of the parser state.
      PARSER_OWNS_TOKEN_SEPS  - Token is assumed to be allocated with malloc(),
                                  calloc(), or realloc(). The token will be
                                  freed when the <a href="#4.1.21">ParserDeInit</a>() is called.


<a name="4.1.02"><font color="blue"><b>4.1.02 - AddTokenSeparator()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> AddTokenSeparator(<font color="blue">const char</font> *sp,
                          <font color="blue">int</font>   Return,
                          <font color="blue">int</font>   switchto,
                          <font color="blue">int</font>   ignore,
                          <font color="blue">char</font> *(*fun)(),
                          <font color="blue">void</font> *params);
  <b>Description:</b>

  <b>Inputs:</b>
   *sp       - Pointer to the string to consider as a separator
    <a href="#Return">Return</a>   - Should the separator be returned by <a href="#4.1.17">Grab</a>/<a href="#4.1.28">PeekToken()</a>? This is
                 useful for filtering out specific strings.
    <a href="#switchto">switchto</a> - Automatically switch to the specified token set, when the token
                 is found. This can also be one of the following defines:
                   PARSER_TSET_DONT_SWITCH - Don't change the current token set
                   PARSER_TSET_LAST        - Switch to the last active token set
    <a href="#ignore">ignore</a>   - If this Token is found, just keep going. Originally designed to
                 be used with strings. For example, \" should be ignored;
                 however, " will be picked out if we don't ignore \"
    <a href="#fun">fun</a>      - Callback function to call when ever the token is found.
    <a href="#params">params</a>   - Pointer to pass to fun. Once a token is found, and Grab*() has
                 returned, <a href="#4.1.08">GetParams</a>() call be called to return this value.

  <b>Output:</b>
    0  - Token has been added to the parser.
    1+ - The specified token is not valid, or another error occurred. This value
           may one or more of the following flags:
             PARSER_TOKEN_NULL          - sp == NULL
             PARSER_OUT_OF_MEMORY       - Could not allocate enough memory to
                                            add the token to parser. This error
                                            will usually cause the rest of the
                                            parser to error out.
             PARSER_REGEX_COMPILE_ERROR - Failed to compile a RegEx to byte code
             PARSER_UNBALANCED_PARENS   - RegEx has unbalanced ()
             PARSER_UNBALANCED_BRACKETS - RegEx has unbalanced []

  <b>Notes:</b>
    The order that tokens are added matters. A token passed in before another
      tokens will be detected first. IE, if you passed in
      AddTokenSep("23");
      AddTokenSep("2");

      "23" will be check for before "2" is checked for.

      This is very useful if you have a token that is a superset of another.

      To change this behavior, call
        <a href="#4.1.23">ParserEnable</a>(PARSER_SORT_TOKEN_SEPS);

      This will cause a weak sorting algorithm to be applied to the tokens
      separator, so that supersets of tokens will always be checked before
      subsets.

    By default, the token that is passed in will be duplicated. To change this
      behavior, call <a href="#4.1.23">ParserEnable</a>(); with one of the
      following defines:

      PARSER_CONST_TOKEN_SEPS - Token is assumed to be constant, and will not
                                  be duplicated or freed. As such, the token
                                  must always be available, for the entire life
                                  of the parser state.
      PARSER_OWNS_TOKEN_SEPS  - Token is assumed to be allocated with malloc(),
                                  calloc(), or realloc(). The token will be
                                  freed when the <a href="#4.1.21">ParserDeInit</a>() is called.

    If ignore is set to 1 and there is a function callback for a token, you will
      not be able to call Grab*() or similar from within the callback.


<a name="4.1.03"><font color="blue"><b>4.1.03 - AddTokenSet()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> AddTokenSet(<font color="blue">void</font>);

  <b>Description:</b>
    Creates a new Token Set, and then sets it as the active one.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    -1 - Error occurred. Call <a href="#4.1.05">ErrorCode()</a> to find out what went wrong.
    0+ - Index of the new token set. Generally, you should use a variable to
           store the return result, and then use that variable when
           <a href="#4.1.35">SetTokenSet()</a> is called.
  <b>Notes:</b>
    N/A


<a name="4.1.04"><font color="blue"><b>4.1.04 - End()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> End(<font color="blue">void</font>);

  <b>Description:</b>
    Returns 1 if the end of the file was reached, a error occurred, or if the
      parser was not initialized.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    1 - The end of the file was reached, a error occurred, or the parser was not
          initialized.
    0 - The parser can still retrieve data from the file.

  <b>Notes:</b>
    N/A


<a name="4.1.05"><font color="blue"><b>4.1.05 - ErrorCode()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> ErrorCode(<font color="blue">void</font>);

  <b>Description:</b>
    Returns a 0 if no error has occurred. Otherwise, an error has occurred.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
            Define              Value           Description
    PARSER_NOT_INITIALIZED     - -1 - Not Initialized. Call <a href="#4.1.24">ParserInit</a>() first.
    PARSER_NO_ERROR            -  0 - No Error
    PARSER_COULD_NOT_OPEN_FILE -  1 - Could not open the specified file.
    PARSER_OUT_OF_MEMORY       -  2 - Could not allocate the required memory
    PARSER_END_OF_FILE         -  3 - Reached the end of the file
    PARSER_MEMORY_NOT_VALID    -  4 - Data passed in to Load Memory was null
    PARSER_GRAB_TOKEN_IGNORE   -  5 - <a href="#4.1.17">GrabToken()</a> or similar was called from a
                                        function callback with ignore set to 1.
                                        This is not supported.

  <b>Notes:</b>
    Check Parser.h for the defines of the above error codes. You can also call
      <a href="#4.1.30">PrintErrorCode()</a> to print out a human readable error code to the
      command prompt. This will be written to stdout via printf().


<a name="4.1.06"><font color="blue"><b>4.1.06 - GetFilePosition()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">long</font> GetFilePosition(<font color="blue">void</font>);

  <b>Description:</b>
    Returns the absolute position of the parser in the file.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Absolute position in the file.

  <b>Notes:</b>
    The position returned will not be accurate if GetFilePosition() is called
      from within a callback that had a token with ignore set to 1.


<a name="4.1.07"><font color="blue"><b>4.1.07 - GetFileSize()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">long</font> GetFileSize(<font color="blue">void</font>);

  <b>Description:</b>
    Returns the size, in bytes, of the currently loaded file or block of memory.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Size of the file/block of memory.

  <b>Notes:</b>
    N/A


<a name="4.1.08"><font color="blue"><b>4.1.08 - GetParams()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void</font> *GetParams(<font color="blue">void</font>);

  <b>Description:</b>
    Returns the params variable associated with the last found token separator.
      This value is the last value specified when you call
      <a href="#4.1.02">AddTokenSeparator</a>().

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Last params variable associated with the last found token separator.

  <b>Notes:</b>
    N/A


<a name="4.1.09"><font color="blue"><b>4.1.09 - GetParserState()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void *</font> GetParserState(<font color="blue">void</font>);

  <b>Description:</b>
    Returns a pointer to the current Parser state.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Pointer to the current Parser state.

  <b>Notes:</b>
    N/A


<a name="4.1.10"><font color="blue"><b>4.1.10 - GetTokenSet()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> GetTokenSet(<font color="blue">void</font>);

  <b>Description:</b>
    Returns the current token set.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    -1 - Parser was not initialized.
    0+ - Current Token Set

  <b>Notes:</b>
    N/A


<a name="4.1.11"><font color="blue"><b>4.1.11 - GrabBinaryFloat()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">float</font> GrabBinaryFloat(<font color="blue">void</font>);

  <b>Description:</b>
    Grabs the next four bytes in the file, and converts them to a float.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Next four bytes in the file as a float. If there are not four bytes left
      in the file, a 0.0f will be returned instead.

  <b>Notes:</b>
    N/A


<a name="4.1.12"><font color="blue"><b>4.1.12 - GrabBinaryInt()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> GrabBinaryInt(<font color="blue">void</font>);

  <b>Description:</b>
    Returns the next <font color="blue">sizeof</font>(int) bytes in the file as an int.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Next <font color="blue">sizeof</font>(int) bytes in the file as an int. If there are less then 4 bytes
      left in the file, a 0 will be returned.

  <b>Notes:</b>
    N/A


<a name="4.1.13"><font color="blue"><b>4.1.13 - GrabByte()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> GrabByte(<font color="blue">void</font>);

  <b>Description:</b>
    Grabs the next character (byte) in the file.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Next character (byte) from the file.

  <b>Notes:</b>
    N/A


<a name="4.1.14"><font color="blue"><b>4.1.14 - GrabBytes()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *GrabBytes(<font color="blue">int</font> bytes);

  <b>Description:</b>
    Grabs the requested number of bytes from the file, and then returns them.

  <b>Inputs:</b>
    bytes - How many bytes to grab from the file.

  <b>Output:</b>
    0  - Requested number of bytes is invalid or the end of the file was reached
    1+ - Pointer to the memory that contains the data from the file.

  <b>Notes:</b>
    You are responsible for cleaning up the data when you are done with it. IE,
      you must call free(&lt;pointer returned by GrabBytes()&gt;).


<a name="4.1.15"><font color="blue"><b>4.1.15 - GrabFloat()</b></font></a>  -  <a href="#top">Top of Page</a>
  Prototype:
    <font color="blue">float</font> GrabFloat(<font color="blue">void</font>);

  <b>Description:</b>
    Grabs the next token in the file, and then attempts to convert it to a float
      via the atof() function declared in stdlib.h. All token separators are
      taken into account. Function callbacks &amp; such will still be called.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Next token converted to a float.

  <b>Notes:</b>
    N/A


<a name="4.1.16"><font color="blue"><b>4.1.16 - GrabInt()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> GrabInt(<font color="blue">void</font>);

  <b>Description:</b>
    Grabs the next token in the file, and then attempts to convert it to an int
      via the atoi() function declared in stdlib.h. All token separators are
      taken into account. Function callbacks &amp; such will still be called.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Next token converted to an int.

  <b>Notes:</b>
    N/A


<a name="4.1.17"><font color="blue"><b>4.1.17 - GrabToken()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *GrabToken(<font color="blue">void</font>);

  <b>Description:</b>
    The main function of the  Parser. This function will scan the file for
      any of the token separators you specified with <a href="#4.1.02">AddTokenSeparator()</a>, as well
      as to apply any specified logic of the token separator.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    0  - End of the file was reached, or an error occurred
    1+ - Character pointer to the next token in the file.

  <b>Notes:</b>
    You are responsible for the cleanup. IE, calling free().


<a name="4.1.18"><font color="blue"><b>4.1.18 - LoadFile()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> LoadFile(<font color="blue">const char</font> *file);

  <b>Description:</b>
    Loads in a new file into the parser for processing.

  <b>Inputs:</b>
    *file - C style string that contains the name/path of the file to parse.

  <b>Output:</b>
    1 - File was loaded and the parser was set up
    0 - Error occurred. Most likely do to an incorrect file name.

  <b>Notes:</b>
    The token sets will not be affected by this function.
    All files are read in as binary.

    By default, the file that is passed in will be duplicated. To change this
      behavior, call <a href="#4.1.23">ParserEnable</a>(); with one of the
      following defines:

      PARSER_CONST_FILE_NAME - File name is assumed to be constant, and will not
                                 be duplicated or freed. As such, the file name
                                 must always be available, for the entire life
                                 of the parser state.
      PARSER_OWNS_FILE_NAME  - File name is assumed to be allocated with
                                 malloc(), calloc(), or realloc(). The file name
                                 will be freed when <a href="#4.1.21">ParserDeInit</a>() is called.


<a name="4.1.19"><font color="blue"><b>4.1.19 - LoadMemory()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> LoadMemory(<font color="blue">const char</font> *memory);

  <b>Description:</b>
    Loads in the specified chunk of memory into the parser for parsing.
      Currently, only C style strings are supported by this function.
    This function calls <a href="#4.1.20">LoadMemoryLen</a>().

  <b>Inputs:</b>
    *memory - Pointer to the chuck of memory to load into the parser.

  <b>Output:</b>
    0 - The specified memory is not valid or the parser was not initialized.
    1 - The memory was loaded into the parser.

  <b>Notes:</b>
    By default, the memory that is passed in will be duplicated. To change this
      behavior, call <a href="#4.1.23">ParserEnable</a>(); with one of the
      following defines:

      PARSER_CONST_LOAD_MEMORY - Memory is assumed to be constant, and will not
                                   be duplicated or freed. As such, the memory
                                   must always be available, for the entire life
                                   of the parser state.
      PARSER_OWNS_LOAD_MEMORY  - Memory is assumed to be allocated with
                                   malloc(), calloc(), or realloc(). The memory
                                   will be freed when <a href="#4.1.21">ParserDeInit</a>() is called.


<a name="4.1.20"><font color="blue"><b>4.1.20 - LoadMemoryLen()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> LoadMemoryLen(<font color="blue">const char</font> *memory, <font color="blue">int</font> len);

  <b>Description:</b>
    Loads in the specified chunk of memory into the parser for parsing.
    Binary based memory can be passed in.

  <b>Inputs:</b>
    *memory - Pointer to the chuck of memory to load into the parser.
     len    - Size of the memory to load into the Parser

  <b>Output:</b>
    0 - The specified memory is not valid or the parser was not initialized.
    1 - The memory was loaded into the parser.

  <b>Notes:</b>
    By default, the memory that is passed in will be duplicated. To change this
      behavior, call <a href="#4.1.23">ParserEnable</a>(); with one of the
      following defines:

      PARSER_CONST_LOAD_MEMORY - Memory is assumed to be constant, and will not
                                   be duplicated or freed. As such, the memory
                                   must always be available, for the entire life
                                   of the parser state.
      PARSER_OWNS_LOAD_MEMORY  - Memory is assumed to be allocated with
                                   malloc(), calloc(), or realloc(). The memory
                                   will be freed when <a href="#4.1.21">ParserDeInit</a>() is called.


<a name="4.1.21"><font color="blue"><b>4.1.21 - ParserDeInit()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void</font> ParserDeInit(<font color="blue">void</font>);

  <b>Description:</b>
    Frees all the memory that the parser was using.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    N/A

  <b>Notes:</b>
    N/A


<a name="4.1.22"><font color="blue"><b>4.1.22 - ParserDisable()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void</font> ParserDisable(<font color="blue">int</font> flags);

  <b>Description:</b>
    Disables one or more features/options.

    See <a href="#2.07">Options/Configuration</a> for a list of defines.

  <b>Inputs:</b>
    One or more features/options to disable. Multiple features can be disabled
      at the same time by | the values together. For example,
        <a href="#4.1.23">ParserEnable</a>(PARSER_REGEX | PARSER_CASE_INSENSITIVE);

  <b>Output:</b>
    N/A

  <b>Notes:</b>
    By default, none of the listed features/options are enabled.


<a name="4.1.23"><font color="blue"><b>4.1.23 - ParserEnable()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void</font> ParserEnable(<font color="blue">int</font> flags);

  <b>Description:</b>
    Enables one or more of the specified options.

    See <a href="#2.07">Options/Configuration</a> for a list of defines.

  <b>Inputs:</b>
    One or more features/options to enable. Multiple features can be enabled
      at the same time by | the values together. For example,
        <a href="#4.1.23">ParserEnable</a>(PARSER_REGEX | PARSER_CASE_INSENSITIVE);

  <b>Output:</b>
    N/A

  <b>Notes:</b>
    By default, none of the listed features/options are enabled.


<a name="4.1.24"><font color="blue"><b>4.1.24 - ParserInit()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void</font> ParserInit(<font color="blue">const char</font> *file, <font color="blue">int</font> bufsize)'

  <b>Description:</b>
    Allocates and initializes all the memory that the parser needs to function.
      Once everything has been allocated and initialized, the Parser will load
      in the requested number of bytes from the file.

  <b>Inputs:</b>
    *file    - Name/Path of the file to load into the parser. A NULL pointer can
                 be passed in if you do not wish to load in an initial file.
     bufsize - How many bytes to read in from the file at one time. If a 0 is
                 passed in, bufsize will default to 1024 - 1 KB. This value
                 can not be changed once it is specified.

  <b>Output:</b>
    N/A

  <b>Notes:</b>
    If this function is called more then once, the parser will automatically
      call <a href="#4.1.21">ParserDeInit()</a>, in order to prevent leaking memory.
      Multiple Parser states can be managed with:
        <a href="#4.1.31">Push</a>/<a href="#4.1.29">PopParserState</a>()
        <a href="#4.1.09">Get</a>/<a href="#4.1.34">SetParserState</a>()


<a name="4.1.25"><font color="blue"><b>4.1.25 - ParserIsEnabled()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> ParserIsEnabled(<font color="blue">int</font> flags);

  <b>Description:</b>
    Checks to see if the specified options/features are enabled. This function
      will return 1 if all the specified options are enabled. If one or more
      options are not enabled, a 0 will be returned.

  <b>Inputs:</b>
    One or more features/options to check if they are enabled. Multiple features
    can be checked at the same time by | the values together. For example,
        <a href="#4.1.23">ParserEnable</a>(PARSER_REGEX | PARSER_CASE_INSENSITIVE);

  <b>Output:</b>
    0 - One or more of the specified options are not enabled.
    1 - All the specified options are enabled.

  <b>Notes:</b>
    See <a href="#2.07">Options/Configuration</a> for a list of defines.


<a name="4.1.26"><font color="blue"><b>4.1.26 - ParserMemoryUsage()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> ParserMemoryUsage(<font color="blue">void</font>);

  <b>Description:</b>
    Returns a estimate of the total number of bytes the current parser state is
      using. Generally, this number will be very accurate; however, certain
      error conditions can skew the results.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Number of bytes of the heap the parser is using.

  <b>Notes:</b>
    Global variable memory is ignored; however, it tends to be very small. By
      default, the Parser only uses 12 * sizeof(void *) bytes of global
      variable memory.


<a name="4.1.27"><font color="blue"><b>4.1.27 - PeekByte()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">unsigned char</font> PeekByte(<font color="blue">int</font> offset);

  <b>Description:</b>
    Returns the next byte + the specified offset in the loaded file/memory. The
      offset can be positive or negative. Requesting a byte before the start
      or after the end of the file/memory will result in a 0.
    This function does not modify the Parsers current location.

  <b>Inputs:</b>
    offset - Offset of the byte to get from the next byte in the file/memory.

  <b>Output:</b>
    Next byte + offset in the stream.

  <b>Notes:</b>
    N/A


<a name="4.1.28"><font color="blue"><b>4.1.28 - PeekToken()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *PeekToken(<font color="blue">void</font>);

  <b>Description:</b>
    Same behavior as <a href="#4.1.17">GrabToken()</a>; although, the parser's position in the file
      is not updated. Callback functions will still be called.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    Pointer to the next token the in file.

  <b>Notes:</b>
    You are responsible for cleaning up the memory when you are done.


<a name="4.1.29"><font color="blue"><b>4.1.29 - PopParserState()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void</font> PopParserState(<font color="blue">void</font>);

  <b>Description:</b>
    Deinitializes the current Parser state, and restores an old state.
      If no old states exist, a new and uninitialized state will be created.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    N/A

  <b>Notes:</b>
    It is safe to pop an empty state stack. This will just cause the current
      state to the deinitialized.


<a name="4.1.30"><font color="blue"><b>4.1.30 - PrintErrorCode()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void</font> PrintErrorCode(<font color="blue">void</font>);

  <b>Description:</b>
    Prints out the current status of the parser to stdout via printf().

    Format:
    &lt;File Name&gt;: &lt;Error Message&gt;

    The file name will be the name of the parser file (Parser.c, by default).
      The error message will be determined by the Error Code.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    N/A

  <b>Notes:</b>
    N/A


<a name="4.1.31"><font color="blue"><b>4.1.31 - PushParserState()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> PushParserState(<font color="blue">void</font>);

  <b>Description:</b>
    Stores the current Parser state, and sets a new/uninitialized Parser state
      as the active state.

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    0 - Could not push the parser state. The hard coded state stack size was
          exceeded. See PARSER_STATE_STACK_SIZE in Parser.c for the
          total number of states the Parser can keep track of.
    1 - Parser State was pushed onto the state stack.

  <b>Notes:</b>
    See PARSER_STATE_STACK_SIZE in Parser.c to change the state stack size.


<a name="4.1.32"><font color="blue"><b>4.1.32 - Seek()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> Seek(<font color="blue">const char</font> *search);

  <b>Description:</b>
    Scans the file for the specified token. If the token is found, the position
      of the parser will be updated to the character directly after the token.
      If the token is not found, nothing in the parser will change.

    PARSER_CASE_INSENSITIVE will be taken into account.

  <b>Inputs:</b>
    *search - C style string to search for in the file.

  <b>Output:</b>
    0 - The token was not found. The parser was not updated.
    1 - The token was found. The parser was updated.

  <b>Notes:</b>
    Token sets are not factored in.
    Globbing and RegEx are not supported by this function.


<a name="4.1.33"><font color="blue"><b>4.1.33 - SetFilePosition()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> SetFilePosition(<font color="blue">long</font> fpos);

  <b>Description:</b>
    Changes the position in the file that the parser scans for the tokens.

  <b>Inputs:</b>
    fpos - Where the parser should start parsing the file.

  <b>Output:</b>
    0 - Error occurred. Call <a href="#4.1.05">ErrorCode()</a> or <a href="#4.1.30">PrintErrorCode()</a> for more info.
    1 - Parser's position was updated.

  <b>Notes:</b>
    N/A


<a name="4.1.34"><font color="blue"><b>4.1.34 - SetParserState()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">void</font> SetParserState(<font color="blue">void</font> *state);

  <b>Description:</b>
    Sets the Parser state to the specified Parser state.

  <b>Inputs:</b>
    *state - State the parser should use.

  <b>Output:</b>
    N/A

  <b>Notes:</b>
    No error checking is done here. The current Parser state will be lost. It is
      highly recommended you call <a href="#4.1.09">GetParserState</a>() before hand
      in order to preserve the last parser state.
    Settings state to 0, followed by calling <a href="#4.1.24">ParserInit()</a> will create a new
      Parser state.


<a name="4.1.35"><font color="blue"><b>4.1.35 - SetTokenSet()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> SetTokenSet(<font color="blue">int</font> tokenset);

  <b>Description:</b>
    Changes the current token set. The following defines can be passed to this
      function:

                Define          Value             Description
        PARSER_TSET_DONT_SWITCH - -1 - Don't change the current token set
        PARSER_TSET_LAST        - -2 - Switch to the last active token set

  <b>Inputs:</b>
    tokenset - Index of the token set to change to.

  <b>Output:</b>
    -1 - The parser was not initialized or the requested token set was not valid
    0+ - Index of the token set switched to.

  <b>Notes:</b>
    N/A


<a name="4.1.36"><font color="blue"><b>4.1.36 - GenericDiscard()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *GenericDiscard()(<font color="blue">char</font> *str, <font color="blue">void</font> *unused);

  <b>Description:</b>
    Generic Parser callback designed to discard the next token. Namely,
     this function simply calls free(<a href="#4.1.17">GrabToken</a>());

  <b>Inputs:</b>
    N/A

  <b>Output:</b>
    0 - Token separator that called the callback was discarded.

  <b>Notes:</b>
    N/A


<div align="center"><a name="4.2"><font color="blue"><b>4.2 - String Manipulation Functions</b></font></a>  -  <a href="#top">Top of Page</a></div>
<div align="center">The following functions are not implemented in string.h
  or operate on different principals.</div>

<a name="4.2.01"><font color="blue"><b>4.2.01 - RemoveWhiteSpaces()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">int</font> RemoveWhiteSpaces(<font color="blue">char</font> *sp);

  <b>Description:</b>
    Removes all spaces, new lines, carriage returns, and tabs from the specified
      string.

  <b>Inputs:</b>
    *sp - string pointer - string to remove the white spaces from.

  <b>Output:</b>
    -1 - sp was not valid
    0+ - New length of the string. The pointer will not be reallocated, so the
           original string pointer should be valid.

  <b>Notes:</b>
    N/A


<a name="4.2.02"><font color="blue"><b>4.2.02 - ToUpper()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
     <font color="blue">char</font> *ToUpper(<font color="blue">char</font> *sp);

  <b>Description:</b>
    Converts a c style string to upper case in place. IE, the string you pass
      in will be directly modified.

  <b>Inputs:</b>
    *sp - pointer to the string to convert to upper case.

  <b>Output:</b>
    Original pointer that was passed in.

  <b>Notes:</b>
    N/A


<a name="4.2.03"><font color="blue"><b>4.2.03 - ToLower()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *ToLower(<font color="blue">char</font> *sp)

  <b>Description:</b>
    Converts a c style string to lower case in place. IE, the string you pass
      in will be directly modified.

  <b>Inputs:</b>
    *sp - pointer to the sting to convert to lower case.

  <b>Output:</b>
    Original pointer that was passed in.

  <b>Notes:</b>
    N/A


<a name="4.2.04"><font color="blue"><b>4.2.04 - Dup()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *Dup(<font color="blue">const char</font> *sp);

  <b>Description:</b>
    Creates a copy of the specified string.

  <b>Inputs:</b>
    *sp - String to make a copy of.

  <b>Output:</b>
    Pointer to the new chunk of memory.

  <b>Notes:</b>
    You are responsible for cleaning up the returned pointer by calling free().


<a name="4.2.05"><font color="blue"><b>4.2.05 - DupLen()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *DupLen(<font color="blue">const char</font> *sp, <font color="blue">int</font> len);

  <b>Description:</b>
    Creates a copy of the specified string. The NULL terminator is automatically
      attached. IE, you can just call strlen(&lt;string&gt;) for the param len.

  <b>Inputs:</b>
    *sp  - String to make a copy of.
     len - Length of the string/position of the null terminator.

  <b>Output:</b>
    Pointer to the new chunk of memory.

  <b>Notes:</b>
    You are responsible for cleaning up the returned pointer by calling free().


<a name="4.2.06"><font color="blue"><b>4.2.06 - DupRange()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *DupRange(<font color="blue">const char</font> *sp, <font color="blue">int</font> start, <font color="blue">int</font> end);

  <b>Description:</b>
    Creates a copy of a specific part of a string

  <b>Inputs:</b>
    *sp    - String to make a partial copy of
     start - Index in the string to start copying data from
     end   - Where to stop/last character to copy

  <b>Output:</b>
    Pointer to the duplicated chunk of the string.

  <b>Notes:</b>
    You are responsible for cleaning up the returned pointer by calling free().


<a name="4.2.07"><font color="blue"><b>4.2.07 - DupRangeFile()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> *DupRangeFile(<font color="blue">const char</font> *file, <font color="blue">int</font> start, <font color="blue">int</font> end);

  <b>Description:</b>
    Opens up the specified file, and then reads in the data range to a buffer.

  <b>Inputs:</b>
    *file  - Name/path of the file to read
     start - Where in the file to start reading in the data
     end   - Where to stop reading in data

  <b>Output:</b>
    0  - The file name was not valid, or the memory couldn't be allocated.
    1+ - Pointer to the new buffer containing the requested data.

  <b>Notes:</b>
    You are responsible for cleaning up the returned pointer by calling free().


<a name="4.2.08"><font color="blue"><b>4.2.08 - Cmp()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Prototype:</b>
    <font color="blue">char</font> Cmp(<font color="blue">const char</font> *osp, <font color="blue">const char</font> *osp2);

  <b>Description:</b>
    Compares two strings together. Cmp() differ from strcmp() (string.h) in two
      ways. First, Cmp() returns a 1 if the strings match, and a 0 if not. 2nd,
      Cmp() is non case sensitive and non white space sensitive.

  <b>Inputs:</b>
    *osp  - First string to compare
    *osp2 - Second string to compare

  <b>Output:</b>
    0 - Strings don't match
    1 - Strings match

  <b>Notes:</b>
    N/A


<div align="center"><a name="4.3"><font color="blue"><b>4.3 - Private Parser Functions</b></font></a>  -  <a href="#top">Top of Page</a></div>
<div align = "center">The following functions are only meant to be called from within
the parser. Making these functions public, and calling them
externally will have undefined results.</div>


<a name="4.3.01"><font color="blue"><b>4.3.01 - BuildRange()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Converts a RegEx range (Ex"[1-4abcd") into a bitfield for easy processing.


<a name="4.3.02"><font color="blue"><b>4.3.02 - Compile()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Compiles a RegEx to its respective byte code.


<a name="4.3.03"><font color="blue"><b>4.3.03 - DisableRegEx()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Disables and restores the original token separator of the specified
      token separator.


<a name="4.3.04"><font color="blue"><b>4.3.04 - DisableWildcard()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Disables and restores the original token separator of the specified
      token separator.



<a name="4.3.05"><font color="blue"><b>4.3.05 - EnableRegEx()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Compiles the specified token separator into a RegEx byte code.


<a name="4.3.06"><font color="blue"><b>4.3.06 - EnableWildcard()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Converts the specified token separator into a easy to consume version of the
      glob/wildcard based separator.


<a name="4.3.07"><font color="blue"><b>4.3.07 - ForwardSearch()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Searches from the current location in the parser for the end of the
      glob/wildcard separator.


<a name="4.3.08"><font color="blue"><b>4.3.08 - ForwardSearchReg()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    RegEx version of ForwardSearch().


<a name="4.3.09"><font color="blue"><b>4.3.09 - GrabLeftover()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Returns any data that was left in the parser. This function is called once
      the end of the file is reached, and no more tokens have been found.


<a name="4.3.10"><font color="blue"><b>4.3.10 - GrabNextChunk()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    This function handles all file input. It will allocate the space for the
      buffer, if required, and then read in the next chunk of the file.


<a name="4.3.11"><font color="blue"><b>4.3.11 - GTChar*()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    These functions are called by GrabToken(). Each function is an optimized
      version of the search algorithms. While this group of functions can
      be reduced to 3 functions, the performance loss is not worth it.


<a name="4.3.12"><font color="blue"><b>4.3.12 - HandleEscapes()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Converts all escape sequences ("\n\r\b...") into an easy to process form.


<a name="4.3.13"><font color="blue"><b>4.3.13 - InvalidRegEx()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Performs some basic syntax check on the specified RegEx.


<a name="4.3.14"><font color="blue"><b>4.3.14 - PDupRangeFile()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Optimized version of <a href="#4.2.07">DupRangeFile</a>() that takes the current Parser state
      into account.


<a name="4.3.15"><font color="blue"><b>4.3.15 - PreserveBufferState()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Preserves the current Parsers location in the file/memory, in order to
      enable forward searching or similar.


<a name="4.3.16"><font color="blue"><b>4.3.16 - PreserveTSetHistory()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Preserves the current token set history to enable forward searching or
      similar.


<a name="4.3.17"><font color="blue"><b>4.3.17 - PrintCompiled()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Prints a compiled RegEx's byte code to the command prompt for debugging
      purposes.


<a name="4.3.18"><font color="blue"><b>4.3.18 - ProcessToken()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    When ever a token is found, the function is called to handle all logic
      attached to the token.


<a name="4.3.19"><font color="blue"><b>4.3.19 - ProcessTokenWild()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    RegEx and Globbing version of <a href="#4.3.18">ProcessToken</a>();


<a name="4.3.20"><font color="blue"><b>4.3.20 - ReadBinary()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Grabs the specified number of bytes from the current Parser state. This
      function is call by GrabBinary*() and GrabBytes().


<a name="4.3.21"><font color="blue"><b>4.3.21 - RebuildHash()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Builds or rebuilds a hash table out of the first character of each token
      separator.


<a name="4.3.22"><font color="blue"><b>4.3.22 - RestoreBufferState()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Restores a state returned from <a href="#4.3.15">PreserveBufferState</a>().


<a name="4.3.23"><font color="blue"><b>4.3.23 - RestoreTSetHistory()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Restores a state returned from <a href="#4.3.16">PreserveTSetHistory</a>().


<a name="4.3.24"><font color="blue"><b>4.3.24 - ShiftRight()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Shifts a RegEx byte code over by the specified number of bytes.


<a name="4.3.25"><font color="blue"><b>4.3.25 - SortTokenSet()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Performs a weak sort on all the token separators. All tokens are sorted
      based on their first character, followed by the length of each token
      separator. This ensures that all supersets of separators will be
      checked before any subsets.


<a name="4.3.26"><font color="blue"><b>4.3.26 - UpdateThreads()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Performs one iteration on a group of RegEx threads.


<a name="4.3.27"><font color="blue"><b>4.3.27 - WriteThreadBefore()</b></font></a>  -  <a href="#top">Top of Page</a>
  <b>Description:</b>
    Writes a RegEx JUMP or THREAD instruction before the specified byte code
      block.


<div align="center"><a name="5.0"><font color="blue"><b>5.0 - Define List</b></font></a>  -  <a href="#top">Top of Page</a></div>
  Returned by <a href="#4.1.05">ErrorCode</a>()
            Define              Value           Description
    PARSER_NOT_INITIALIZED     - -1 - Not Initialized. Call <a href="#4.1.24">ParserInit</a>() first.
    PARSER_NO_ERROR            -  0 - No Error
    PARSER_COULD_NOT_OPEN_FILE -  1 - Could not open the specified file.
    PARSER_OUT_OF_MEMORY       -  2 - Could not allocate the required memory
    PARSER_END_OF_FILE         -  3 - Reached the end of the file
    PARSER_MEMORY_NOT_VALID    -  4 - Data passed in to Load Memory was null
    PARSER_GRAB_TOKEN_IGNORE   -  5 - <a href="#4.1.17">GrabToken()</a> or similar was called from a
                                        function callback with ignore set to 1.
                                        This is not supported.


  <a href="#4.1.02">AddTokenSeparator</a>() <a href="#switchto">SwitchTo</a> defines:
            Define           Value           Description
    PARSER_TSET_DONT_SWITCH - -1 - Don't change the current TSet
    PARSER_TSET_LAST        - -2 - Switch to the last active TSet


  <a href="#4.1.02">AddTokenSeparator</a>() return values:
          Define                          Description
    PARSER_NO_ERROR            - Token has been added.
    PARSER_TOKEN_NULL          - Token is NULL/0, and thus invalid
    PARSER_OUT_OF_MEMORY       - Could not allocate enough memory for the token
    PARSER_REGEX_COMPILE_ERROR - Could not compile the given RegEx
    PARSER_UNBALANCED_PARENS   - Unbalanced () in RegEx
    PARSER_UNBALANCED_BRACKETS - Unbalanced [] in RegEx

  Parser <a href="#2.07">Options - See Options/Configuration</a> for descriptions
    PARSER_HASH
    PARSER_CASE_INSENSITIVE
    PARSER_WILDCARD
    PARSER_GLOBBING
    PARSER_REGULAR_EXPRESSIONS
    PARSER_REGEX
    PARSER_CLOSE_FILE
    PARSER_SORT_TOKEN_SEPS
    PARSER_CONST_FILE_NAME
    PARSER_CONST_LOAD_MEMORY
    PARSER_CONST_TOKEN_SEPS
    PARSER_OWNS_FILE_NAME
    PARSER_OWNS_LOAD_MEMORY
    PARSER_OWNS_TOKEN_SEPS

  Other:
    PARSER_CALLBACK - Typedef of the Parser Callback prototype.
    PCBACK          - Same as PARSER_CALLBACK


<div align="center"><a name="6.0"><font color="blue"><b>6.0 - Known Bugs</b></font></a>  -  <a href="#top">Top of Page</a></div>
  RegEx Bugs:
    Parser can enter infinite loop
      Example: ".*" - Will always succeed without removing any characters from
                        the stream.

  PeekToken() calls callbacks

  If a token sep is set to ignore, any related callback may be called multiple
    times for the same set of bytes in file.


<div align="center"><a name="7.0"><font color="blue"><b>7.0 - Planned Features</b></font></a>  -  <a href="#top">Top of Page</a></div>
  RegEx:
    Capture Groups
    Backreferences

  Parsing Methods:
    LALR

  Ability to modify existing Token Separators

  C++ Wrapper:
    Use new and delete internally
    return std::auto_ptr&lt;char *&gt; (std::string would duplicate the string)

  Save Parser State As:
    External Text File and Text Stream:
      Human Readable and Easy To Edit
    External Binary File and Byte Stream:
      Fast and Small.
      All preprocessing already done.
    Issues:
      Parser Callbacks &amp; Params.
        Function and Var registry?
    Pluses:
      No recompilation required to change how the parser works

  External Script File


<div align="center"><a name="8.0"><font color="blue"><b>8.0 - Change Log</b></font></a>  -  <a href="#top">Top of Page</a></div>
  Parser v 8.9
    Massive Performance Boosts across the board
    Runtime configurable options
      Case Insensitivity
      Hashing
      <a href="#glob">Globbing</a>
      <a href="#regex">RegEx</a> (Work In Progress)
      Some Memory Management
      Close File After Read
    Callback:
      Takes   char * - matched token sep
      returns char * - value GrabToken() should return
    Added <a href="#4.1.08">GetParams</a>();
    Added <a href="#4.1.07">GetFileSize</a>();
    General Bug Fixes
    Reduced Indirection in Internal Structs
    C++ Wrapper:
      Implemented Copy Constructor
    Smarter Cashing
      Fixed long standing GrabBinary*() buffer size limitation
    GrabChar() -&gt; <a href="#4.1.13">GrabByte</a>(), due to confusion
    Removed DeSmet C support

  Parser v 8.0
    Function callback is now passed a void *
      - <a href="#4.1.02">AddTokenSeparator()</a> now takes a additional parameter
    Restricted <a href="#4.1.17">GrabToken()</a> from callback from Token with ignore == 1
      This would cause an infinite recursion loop.
    Fixed a possible buffer over read
    Token order is now preserved correctly
    Various Optimizations
    Bulk of String Manipulation Functions now use const when possible

    Performance Delta:
      GNU: ~6% Faster
      MS : No performance difference

    Note: A few new warnings have been introduced, and need to be fixed

  Parser v 7.1
    Bug fix relating to recursion caused by Parser callback function calling
      GrabToken().
    Added <a href="#4.1.09">Get</a>/<a href="#4.1.34">SetParserState()</a>
    Added <a href="#4.1.36">GenericDiscard()</a> Parser callback, since it is
      a fairly common function.

  Parser v 7.0
    Moved most of the documentation to this html file
    A few bug/broke logic fixes

  Parser v 6.0
    Dropped C++ build
    Added DeSmet C support - strict ANSI C
    Several bug/broken logic fixes
    Reduced requested frees and allocs by ~66%
    Massive Code Cleanup
    Removed a lot of redundant code
    Improved internal error handler
    Added function callbacks
    Cleaned up documentation

  Parser v 5.0
    Began testing on Linux
    Several bug/broken logic fixes
    Massive performance boost to internal file handler (~60% faster!)

  Parser v 4.0
    Implemented binary support
    Expanded internal File Handler
      Load Files Dynamically
      Load Memory Dynamically
    Improved Internal Error Handler

  Parser v 3.0
    Implemented internal File Handler

  Parser v 2.0
    Added a C++ build
    Added the bulk of the String Manipulation Functions

  Parser v 1.0 - Original build with
    Multiple Token Set Support
    Token Separators with logic:
      Return
      switchto
      ignore

</body>
</html>
